/**
 * Copyright (c) Glodon Co. Ltd.
 */
package com.cws.service;


import java.util.List;
import java.util.Map;

import com.cws.dao.IBaseDAO;
import com.cws.model.Page;

/**
 * 对外部提供服务接口调用的类定义
 * 
 * <p>
 * <b>创建日期</b> 2011年12月6日
 * </p>
 * @author lysming
 * @since 3.0.1-SNAPSHOT
 */
public interface IBaseService {

    /**
     * 获取进行数据库对象访问操作的对象
     * @return 数据库对象访问操作的对象
     */
    IBaseDAO getBaseDAO();
    
    /**
     * 保存一条记录
     * @param po 要保存的对象
     * @return 保存成功返回 true， 否则返回 false
     */
    boolean save(Object po);

    /**
     * 根据主键更新一条记录
     * @param po 要更新的记录，主键值必须不为 null
     * @return 更新成功返回 true， 否则返回 false
     */
    boolean update(Object po);

    /**
     * 根据主键删除一条记录
     * @param po 要删除的对象
     * @return 删除成功返回 true， 否则返回 false
     */
    boolean delete(Object po);
    
    /**
     * 根据主键查询一条记录
     * @param poClass PO 类定义
     * @param id 主键值
     * @param <T> 数据记录对应的 javaBean 类型
     * @return 查询到的对象，如果没有匹配记录则返回 null
     */
    <T> T get(Class<T> poClass, String id);
    
    /**
     * 通用分页查询
     * 
     * @param params 检索条件，如：<pre><code>new String[][]{
     *      {User.class},
     *      {QuerySupport.PAGE, "1"},
     *      {QuerySupport.PAGESIZE, "20"}
     * }</code></pre>
     * @return 包含符合条件的数据记录的分页对象
     * @deprecated 已由 {@link #getAsPage2(Map)} 方法替代
     */
    Page<?> getAsPage(String[][] params);

    /**
     * 通用分页查询
     * 
     * @param queryParams 检索条件，该 Map 中必须包含如下 key：
     *            <ul>
     *            <li>TABLENAME - 要查询的 PO 或 VO 的类定义</li>
     *            <li>PAGE - 页码</li>
     *            <li>PAGESIZE - 每页显示的记录条数</li>
     *            </ul>
     * @return 包含符合条件的数据记录的分页对象
     * @deprecated 已由 {@link #getAsPage2(Map)} 方法替代
     */
    Page<?> getAsPage(Map<String, ?> queryParams);
    
    /**
     * 通用分页查询。该方法与 {@link #getAsPage(Map)}
     * 唯一的区别就是该方法的返回类型支持泛型，无需在调用方法后对查询到的结果集合进行类型强转
     * 
     * @param queryParams 检索条件，该 Map 中必须包含如下 key：
     *            <ul>
     *            <li>TABLENAME - 要查询的 PO 或 VO 的类定义</li>
     *            <li>PAGE - 页码</li>
     *            <li>PAGESIZE - 每页显示的记录条数</li>
     *            </ul>
     * @param <T> 返回结果对应的 PO 或 VO 的类型
     * @return 包含符合条件的数据记录的分页对象
     */
    <T> Page<T> getAsPage2(Map<String, ?> queryParams);

    /**
     * 通用列表查询
     * 
     * @param params 查询条件，如：<pre><code>new String[][]{
     *      {User.class},
     *      {"_username", "hemw"},
     *      {"_status", UserStatus.VALID}
     * }</code></pre>
     * @return 查询结果
     * @deprecated 已经由方法 {@link #query2(Map)} 替代
     */
    List<?> query(String[][] params);

    /**
     * 通用列表查询
     * 
     * @param queryParams 查询条件
     * @return 查询结果
     * @deprecated 已经由方法 {@link #query2(Map)} 替代
     */
    List<?> query(Map<String, ?> queryParams);
    
    /**
     * 通用列表查询。该方法与 {@link #query(Map)} 方法唯一的区别就是该方法的返回类型支持泛型，无需在调用方法后对查询到的结果集合进行类型强转
     * 
     * @param queryParams 查询条件
     * @param <T> 查询结果中的数据记录对应的 PO 或 VO 的类型
     * @return 查询结果列表
     */
    <T> List<T> query2(Map<String, ?> queryParams);

    /**
     * 查询指定 PO 对应的表中的总数据记录条数
     * 
     * @param clazz PO 实体类
     * @param field 查询此字段的条数，最好采用主键或索引字段
     * @return 总记录条数
     */
    Long getCount(Class<?> clazz, String field);

    /**
     * 查询符合条件的数据记录条数
     * 
     * @param queryParams 查询参数，与 {@link #query(Map)} 方法的参数一致
     * @return 符合检索条件的记录条数
     * @see #query(Map)
     */
    Long getCount(Map<String, Object> queryParams);

    /**
     * 根据 SQL 或 HQL 语句查询符合条件的记录条数
     * @param hql HQL 查询语句
     * @param params 查询条件的参数
     * @return 符合条件的记录数
     */
    long getCount(String hql, Map<String, Object> params);
    
    /**
     * 根据 SQL 语句查询符合条件的记录条数
     * @param sql 原生的 SQL 查询语句，类似于 select ... from tableName where ...
     * @param params 查询条件
     * @return 符合查询条件的总记录数
     */
    long getCountBySql(String sql, Map<String, ?> params);
}
